

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>AG_fft_tools.convolve &mdash; agpy 0.1.2 documentation</title>
    
    <link rel="stylesheet" href="../../_static/extra.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '0.1.2',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <link rel="top" title="agpy 0.1.2 documentation" href="../../index.html" />
    <link rel="up" title="Module code" href="../index.html" />
     
    <script type="text/javascript">

      var _gaq = _gaq || [];
      _gaq.push(['_setDomainName', 'pyspeckit.bitbucket.org']);
      _gaq.push(['_setAllowHash', false]);
      _gaq.push(['_trackPageview']);


    </script>
    <link rel="stylesheet" type="text/css" href="../../_static/extra.css" />
  </head>
  <body>
    <div class="header-wrapper">
      <div class="header">
        <h1><a href="../../index.html">agpy 0.1.2 documentation</a></h1>
        <div class="rel">
          <a href="http://agpy.googlecode.com">agpy Home </a>  |
          <a href=../../index.html>Docs Home </a>  |
          <a href="http://code.google.com/p/agpy/w/list">Wiki</a>  |
          <a href=../../search.html>Search </a>
        </div>
       </div>
    </div>

    <div class="content-wrapper">
      <div class="content">
        <div class="document">
            
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <h1>Source code for AG_fft_tools.convolve</h1><div class="highlight"><pre>
<div class="viewcode-block" id="convolve"><a class="viewcode-back" href="../../fft_tools.html#AG_fft_tools.convolve.convolve">[docs]</a><span class="k">def</span> <span class="nf">convolve</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="n">kernel</span><span class="p">,</span> <span class="n">boundary</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">fill_value</span><span class="o">=</span><span class="mf">0.</span><span class="p">,</span>
             <span class="n">normalize_kernel</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;</span>
<span class="sd">    Convolve an array with a kernel</span>

<span class="sd">    This routine differs from scipy.ndimage.convolve because it includes a</span>
<span class="sd">    special treatment for NaN values. Rather than including NaNs in the</span>
<span class="sd">    convolution calculation, which causes large NaN holes in the convolved</span>
<span class="sd">    image, NaN values are replaced with interpolated values using the kernel</span>
<span class="sd">    as an interpolation function.</span>

<span class="sd">    Parameters</span>
<span class="sd">    ----------</span>
<span class="sd">    array: np.ndarray</span>
<span class="sd">        The array to convolve. This should be a 1, 2, or 3-dimensional array</span>
<span class="sd">        or a list or a set of nested lists representing a 1, 2, or</span>
<span class="sd">        3-dimensional array.</span>
<span class="sd">    kernel: np.ndarray</span>
<span class="sd">        The convolution kernel. The number of dimensions should match those</span>
<span class="sd">        for the array, and the dimensions should be odd in all directions.</span>
<span class="sd">    boundary: str, optional</span>
<span class="sd">        A flag indicating how to handle boundaries:</span>
<span class="sd">            * None : set the ``result`` values to zero where the kernel</span>
<span class="sd">                     extends beyond the edge of the array (default)</span>
<span class="sd">            * &#39;fill&#39; : set values outside the array boundary to fill_value</span>
<span class="sd">            * &#39;wrap&#39; : periodic boundary</span>
<span class="sd">            * &#39;extend&#39; : set values outside the array to the nearest array</span>
<span class="sd">                         value</span>
<span class="sd">    fill_value: float, optional</span>
<span class="sd">        The value to use outside the array when using boundary=&#39;fill&#39;</span>
<span class="sd">    normalize_kernel: bool, optional</span>
<span class="sd">        Whether to normalize the kernel prior to convolving</span>

<span class="sd">    Returns</span>
<span class="sd">    -------</span>
<span class="sd">    result, np.ndarray</span>
<span class="sd">        An array with the same dimensions and type as the input array,</span>
<span class="sd">        convolved with kernel.</span>

<span class="sd">    Notes</span>
<span class="sd">    -----</span>
<span class="sd">    Masked arrays are not supported at this time.</span>
<span class="sd">    &#39;&#39;&#39;</span>

    <span class="c"># Check that the arguemnts are lists or Numpy arrays</span>
    <span class="k">if</span> <span class="nb">type</span><span class="p">(</span><span class="n">array</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">:</span>
        <span class="n">array</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
    <span class="k">elif</span> <span class="nb">type</span><span class="p">(</span><span class="n">array</span><span class="p">)</span> <span class="o">!=</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">&quot;array should be a list or a Numpy array&quot;</span><span class="p">)</span>
    <span class="k">if</span> <span class="nb">type</span><span class="p">(</span><span class="n">kernel</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">:</span>
        <span class="n">kernel</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">kernel</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
    <span class="k">elif</span> <span class="nb">type</span><span class="p">(</span><span class="n">kernel</span><span class="p">)</span> <span class="o">!=</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">&quot;kernel should be a list or a Numpy array&quot;</span><span class="p">)</span>

    <span class="c"># Check that the number of dimensions is compatible</span>
    <span class="k">if</span> <span class="n">array</span><span class="o">.</span><span class="n">ndim</span> <span class="o">!=</span> <span class="n">kernel</span><span class="o">.</span><span class="n">ndim</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">&#39;array and kernel have differing number of&#39;</span>
                        <span class="s">&#39;dimensions&#39;</span><span class="p">)</span>

    <span class="c"># The .dtype.type attribute returs the datatype without the endian. We can</span>
    <span class="c"># use this to check that the arrays are 32- or 64-bit arrays</span>
    <span class="k">if</span> <span class="n">array</span><span class="o">.</span><span class="n">dtype</span><span class="o">.</span><span class="n">kind</span> <span class="o">==</span> <span class="s">&#39;i&#39;</span><span class="p">:</span>
        <span class="n">array</span> <span class="o">=</span> <span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>
    <span class="k">elif</span> <span class="n">array</span><span class="o">.</span><span class="n">dtype</span><span class="o">.</span><span class="n">kind</span> <span class="o">!=</span> <span class="s">&#39;f&#39;</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">&#39;array should be an integer or a &#39;</span>
                        <span class="s">&#39;floating-point Numpy array&#39;</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">kernel</span><span class="o">.</span><span class="n">dtype</span><span class="o">.</span><span class="n">kind</span> <span class="o">==</span> <span class="s">&#39;i&#39;</span><span class="p">:</span>
        <span class="n">kernel</span> <span class="o">=</span> <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>
    <span class="k">elif</span> <span class="n">kernel</span><span class="o">.</span><span class="n">dtype</span><span class="o">.</span><span class="n">kind</span> <span class="o">!=</span> <span class="s">&#39;f&#39;</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">&#39;kernel should be an integer or a &#39;</span>
                        <span class="s">&#39;floating-point Numpy array&#39;</span><span class="p">)</span>

    <span class="c"># Because the Cython routines have to normalize the kernel on the fly, we</span>
    <span class="c"># explicitly normalize the kernel here, and then scale the image at the</span>
    <span class="c"># end if normalization was not requested.</span>
    <span class="n">kernel_sum</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">kernel</span><span class="p">)</span>
    <span class="n">kernel</span> <span class="o">/=</span> <span class="n">kernel_sum</span>

    <span class="c"># The cython routines are written for np.flaot, but the default endian</span>
    <span class="c"># depends on platform. For that reason, we first save the original</span>
    <span class="c"># array datatype, cast to np.float, then convert back</span>
    <span class="n">array_dtype</span> <span class="o">=</span> <span class="n">array</span><span class="o">.</span><span class="n">dtype</span>

    <span class="k">if</span> <span class="n">array</span><span class="o">.</span><span class="n">ndim</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">&quot;cannot convolve 0-dimensional arrays&quot;</span><span class="p">)</span>
    <span class="k">elif</span> <span class="n">array</span><span class="o">.</span><span class="n">ndim</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;extend&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve1d_boundary_extend</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                                <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
        <span class="k">elif</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;fill&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve1d_boundary_fill</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="nb">float</span><span class="p">(</span><span class="n">fill_value</span><span class="p">))</span>
        <span class="k">elif</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;wrap&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve1d_boundary_wrap</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve1d_boundary_none</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
    <span class="k">elif</span> <span class="n">array</span><span class="o">.</span><span class="n">ndim</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;extend&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve2d_boundary_extend</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                                <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
        <span class="k">elif</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;fill&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve2d_boundary_fill</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="nb">float</span><span class="p">(</span><span class="n">fill_value</span><span class="p">))</span>
        <span class="k">elif</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;wrap&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve2d_boundary_wrap</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve2d_boundary_none</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
    <span class="k">elif</span> <span class="n">array</span><span class="o">.</span><span class="n">ndim</span> <span class="o">==</span> <span class="mi">3</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;extend&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve3d_boundary_extend</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                                <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
        <span class="k">elif</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;fill&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve3d_boundary_fill</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="nb">float</span><span class="p">(</span><span class="n">fill_value</span><span class="p">))</span>
        <span class="k">elif</span> <span class="n">boundary</span> <span class="o">==</span> <span class="s">&#39;wrap&#39;</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve3d_boundary_wrap</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">convolve3d_boundary_none</span><span class="p">(</span><span class="n">array</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">),</span>
                                              <span class="n">kernel</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">))</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">raise</span> <span class="bp">NotImplemented</span><span class="p">(</span><span class="s">&#39;convolve only supports 1, 2, and 3-dimensional &#39;</span>
                             <span class="s">&#39;arrays at this time&#39;</span><span class="p">)</span>

    <span class="c"># If normalization was not requested, we need to scale the array (since</span>
    <span class="c"># the kernel was normalized prior to convolution)</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="n">normalize_kernel</span><span class="p">:</span>
        <span class="n">result</span> <span class="o">*=</span> <span class="n">kernel_sum</span>

    <span class="c"># Cast back to original dtype and return</span>
    <span class="k">return</span> <span class="n">result</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span><span class="n">array_dtype</span><span class="p">)</span></div>
</pre></div>

          </div>
        </div>
      </div>
        </div>
        <div class="sidebar">
          <h3>Table Of Contents</h3>
          <ul>
<li class="toctree-l1"><a class="reference internal" href="../../agpy.html">Adam Ginsburg&#8217;s Python Code (agpy)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../image_tools.html">Image Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fft_tools.html">AG_fft_tools Package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../plfit.html">plfit Package</a></li>
</ul>

          <h3 style="margin-top: 1.5em;">Search</h3>
          <form class="search" action="../../search.html" method="get">
            <input type="text" name="q" />
            <input type="submit" value="Go" />
            <input type="hidden" name="check_keywords" value="yes" />
            <input type="hidden" name="area" value="default" />
          </form>
          <p class="searchtip" style="font-size: 90%">
            Enter search terms or a module, class or function name.
          </p>
        </div>
        <div class="clearer"></div>
      </div>
    </div>

    <div class="footer">
      &copy; Copyright 2011, Adam Ginsburg.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
    <script type="text/javascript">

      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-6253248-2']);
      _gaq.push(['_trackPageview']);

      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();

    </script>
        
    </div>
  </body>
</html>